<html>
<head><meta charset="utf-8"><title>Mini RFC: Update lint documentation syntax · clippy · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/257328-clippy/index.html">clippy</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/257328-clippy/topic/Mini.20RFC.3A.20Update.20lint.20documentation.20syntax.html">Mini RFC: Update lint documentation syntax</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="238516191"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/257328-clippy/topic/Mini%20RFC%3A%20Update%20lint%20documentation%20syntax/near/238516191" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> xFrednet <a href="https://rust-lang.github.io/zulip_archive/stream/257328-clippy/topic/Mini.20RFC.3A.20Update.20lint.20documentation.20syntax.html#238516191">(May 12 2021 at 17:50)</a>:</h4>
<p>Hello everyone, I'm currently working on a new metadata collector for Clippy to collect lint documentation, configuration etc. The next step it to adapt the website and I wanted to get your opinion on the documentation syntax. (Tracking issue <a href="https://github.com/rust-lang/rust-clippy/issues/7172">rust-clippy#7172</a>)</p>
<p>Clippy's lint documentation currently uses bold text via <code>**&lt;headline&gt;**</code> to define a headline. This is a bit uncommon for Markdown and would require more specific handling. The current website uses several loops to display this correctly, which is probably also a reason for the comparatively slow loading times.</p>
<p>I would like to update the entire lint documentation to use the Markdown headlines <code>### &lt;headline&gt;</code> instead. This would simplify the implementation and also align us with rustc's documentation style (See <a href="https://github.com/rust-lang/rust/blob/7a0f1781d04662041db5deaef89598a8edd53717/compiler/rustc_lint/src/builtin.rs#L833-L879">example</a>). What are your thought's about it?</p>



<a name="238516888"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/257328-clippy/topic/Mini%20RFC%3A%20Update%20lint%20documentation%20syntax/near/238516888" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> flip1995 <a href="https://rust-lang.github.io/zulip_archive/stream/257328-clippy/topic/Mini.20RFC.3A.20Update.20lint.20documentation.20syntax.html#238516888">(May 12 2021 at 17:55)</a>:</h4>
<p>Since the documentation is displayed in a header style on the website anyway  this would definitely make sense. <span class="user-mention" data-user-id="360405">@Cameron Steffen</span> also suggested to change this recently as part of his PoC PR moving lint doc to separate files.</p>
<p>I only see advantages we'd get from this change, so this is definitely a YES from me.</p>



<a name="238709030"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/257328-clippy/topic/Mini%20RFC%3A%20Update%20lint%20documentation%20syntax/near/238709030" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Cameron Steffen <a href="https://rust-lang.github.io/zulip_archive/stream/257328-clippy/topic/Mini.20RFC.3A.20Update.20lint.20documentation.20syntax.html#238709030">(May 14 2021 at 02:24)</a>:</h4>
<p>Yup SGTM. I suggested two <code>##</code> but I guess it's arbitrary <span aria-label="shrug" class="emoji emoji-1f937" role="img" title="shrug">:shrug:</span></p>



<a name="239103181"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/257328-clippy/topic/Mini%20RFC%3A%20Update%20lint%20documentation%20syntax/near/239103181" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> xFrednet <a href="https://rust-lang.github.io/zulip_archive/stream/257328-clippy/topic/Mini.20RFC.3A.20Update.20lint.20documentation.20syntax.html#239103181">(May 17 2021 at 14:52)</a>:</h4>
<p>Awesome! I'll make the switch when the metadata collection is up in running and then create a PR for it.</p>
<p>The choice of using three hashtags was mostly based on the lint doc syntax inside the compiler. They most likely choose this syntax to build the following hierarchy:</p>
<ol>
<li>Lint group (for instance <em>Allowed-by-default lints</em>)</li>
<li>Lint name (for instance <em>anonymous-parameters</em>)</li>
<li>Lint documentation extracted from the doc comment</li>
</ol>
<p>Example: <a href="https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#anonymous-parameters">here</a>. I think it's reasonable to do the same in case we want to switch over to MdBook at some point in time</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>